Release 10.1A: OpenEdge Development:
Debugging and Troubleshooting

New Breakpoint dialog box

The New Breakpoint dialog box lets you set new breakpoints and watchpoints.

Access this dialog box by choosing the New button on the Breakpoints dialog box. For more information, see the "Breakpoints dialog box" section.

The New Breakpoint dialog box contains the following tabs:

At Line — Sets a breakpoint at a specific line in a named procedure. You can make this type of breakpoint conditional; that is, it interrupts program execution only if a defined condition is satisfied. A breakpoint indicator appears in red in the shaded area to the left of each line in the source code pane where an At Line breakpoint is set. Figure 3–14 shows the New Breakpoint dialog box with the At Line tab.



Figure 3–14: New Breakpoint dialog box with At Line
On Error — Sets a breakpoint to interrupt program execution if an error occurs. The error condition can be general or specific. Figure 3–15 shows the New Breakpoint dialog box with the On Error tab.



Figure 3–15: New Breakpoint dialog box with On Error

For more information on setting breakpoints if an error occurs, see the "Setting an error-based breakpoint" section.

Watchpoint — Sets a watchpoint to interrupt program execution when the value of a variable, buffer field or attribute reference changes. Figure 3–16 shows the New Breakpoint dialog box with the Watchpoint tab.



Figure 3–16: New Breakpoint dialog box with Watchpoint

Setting a breakpoint in a procedure

To add a breakpoint at a specific line in a named procedure:

In the New Breakpoint dialog box, select the At Line tab.
Enter the name of an OpenEdge procedure.
Enter an integer that specifies a line number in the current or specified procedure.
Specify a condition that must be satisfied for the breakpoint to be honored (optional).
Choose the OK button.

A breakpoint indicator appears in red in the shaded area to the left of each line in the source code pane where a breakpoint is set. You can also add a breakpoint by clicking in the shaded area to the left of a line in the source code pane directly.

Procedure names and line numbers

Consider the following when setting a breakpoint:

If you specify only a procedure name, the breakpoint is set on the first executable line of the procedure.
If you do not specify a procedure name, the breakpoint is set on the specified line in the procedure currently displayed in the source code pane.
If you specify a line number that is before any executable line in the code for the active procedure in the Debugger context, the breakpoint is set on the first executable line on or after the specified line. For example, if you specify line number 10 for an active procedure displayed with the following lines, the breakpoint is actually set on line 12:

10 /* Set Startup Temperature */ 11 DEFINE VARIABLE InitialTemp AS INTEGER. 12 ASSIGN InitialTemp = 32.

If there is no executable line on or after the specified line, the breakpoint is set on the last executable line. For example, if you specify line number 20 for the lines displayed above, the breakpoint is also set on line 12.

If you specify a line number for an inactive procedure, the breakpoint is set on the specified line. When the procedure becomes active in the Debugger context, the specified breakpoint adjusts to the corresponding effective breakpoint line.
When setting a breakpoint, there is a distinction between specifying a line number value less than 1 and specifying a value of 1 or more. Any value less than 1 (for example, 0 or –1) specifies the first executable line of the main procedure in the procedure file. Any positive value specifies the first executable line on or after the specified line in the procedure file. For example, suppose the procedure file starts out like this:

1 DEFINE VARIABLE lStart AS LOGICAL INITIAL TRUE. 2 PROCEDURE ShowStart: 3 IF lStart THEN MESSAGE "Procedure is starting ...". 4 END. 5 6 MESSAGE "Hello World!". 7 RUN ShowStart. 8 lStart = FALSE. . . .

If you specify a breakpoint at line 0, –1, or any other negative value, the breakpoint actually occurs at line 6, the first line that executes in the main procedure. If you specify a breakpoint at line 1 or 2, the breakpoint occurs at line 3, the first executable line after 1 and 2, which happens to be the first executable line of an internal procedure.

This distinction also affects procedures containing the trigger phrase used to define triggers in object definitions. For example, suppose the procedure file starts out like this:

1 DEFINE BUTTON bOK LABEL "OK" 2 TRIGGERS: 3 ON CHOOSE 4 MESSAGE "OK Pressed!". 5 END TRIGGERS. 6 MESSAGE "Hello World!". . . .

Again, if you specify a breakpoint at line –1, the breakpoint occurs on line 6, but if you specify the breakpoint at line 1, it occurs at line 4, which is the first executable line of a trigger block.

Conditional breakpoints

A condition is any expression that the 4GL interpreter can evaluate to a logical value. The expression can include variables, buffer fields, object methods and attributes, logical operators (AND, OR, and so forth), comparison operators (=, <>, EQ, NE, and so forth), and other code entities.

The 4GL interpreter validates the expression syntax when the breakpoint is added, but does not check variable references. If any variables in the condition are out-of-scope or nonexistent, the interpreter interrupts execution (as if honoring the breakpoint) and displays an error message in the Debugger.

If the expression attempts to execute an I/O blocking statement (for example, a user-defined function that includes an UPDATE statement), the 4GL interpreter displays an error message over the application window, not in the Debugger window. Note in this case that code in the user-defined function preceding the UPDATE statement is executed.

You can add a condition to any existing breakpoint (except those that are triggered by an error) by selecting the breakpoint and choosing the Edit button in the Breakpoints dialog box. For more information, see the "Edit Breakpoint dialog box" section.

Setting an error-based breakpoint

To add a breakpoint triggered by an error:

In the New Breakpoint dialog box, select the On Error tab. Select the appropriate radio button, as follows:
Any Unsuppressed Error — The Debugger gains control on the occurrence of any error not suppressed by a NO-ERROR. This type of breakpoint appears in the Breakpoints list as “Break on any unsuppressed error.”
Any Error — The Debugger gains control on the occurrence of any error regardless of whether the error is suppressed by a NO-ERROR. This type of breakpoint appears in the Breakpoints list as “Break on any error.”
On Error — The Debugger gains control on the occurrence of the specifically identified error, regardless of whether the error is suppressed by a NO-ERROR. This type of breakpoint appears in the Breakpoints list as “Break on Error #nnnnn.”
Enter an integer of 1–5 digits that identifies a specific error (available, and required, only when On Error is selected).
Choose the OK button.

Breakpoints triggered by errors

Consider the following when setting breakpoints based on errors:

For any breakpoint triggered by an error, an alert box appears stating “Stopped due to Break on error nnnnn.” (the error number appears for all three types). The Debugger gains control at the next executable line following the line of 4GL code that caused the error.
Note: For On Error, the Debugger ensures that you entered a number from 1–99999, but otherwise does not verify that an error corresponding to the number exists.
Errors that occur in hidden procedures, that is, procedures whose filenames begin with an underscore (_), such as the ADE tools, do not trigger error breakpoints.
If your program does not trap a stop condition (with ON STOP, for example), the Debugger ignores the error that causes the interruption, since the program terminates. Similarly, the Debugger ignores an error condition that is not trapped (with ON ERROR, for example) and results in program termination.

Setting a watchpoint

To add a watchpoint:

In the New Breakpoint dialog box, select the Watchpoint tab.
Type the name of a variable, buffer field, object attribute, or object reference in the Expression field. You can optionally add a condition in the Condition field.
Note: A watchpoint requires a watchpoint expression. If you do not enter an expression and choose OK, an error message appears in an alert box.
Choose OK to create the watchpoint.

Watchpoints appear in the Breakpoints dialog box as “When expression changes [and condition]”. The third and fourth items in Figure 3–17 are watchpoints.

Figure 3–17: Watchpoint example

Entering a watchpoint automatically creates a watch for the watchpoint expression. If you leave the Add Watch toggle checked, the Debugger displays the watch in the Watches pane of the Debugger's main window. You can uncheck the Add Watch toggle box to override this behavior (Add Watch is checked by default). The Debugger shows the current value of all watches each time the Debugger gains control of the application.

Note: The watch and watchpoint are not connected to each other. Deleting the watchpoint does not delete the watch. Deleting the watch does not delete the watchpoint.

If the watchpoint expression or condition is invalid, the Debugger creates the watchpoint and displays an error message. In this case, edit the watchpoint and correct the mistake. If you do not fix the watchpoint before continuing program execution, the 4GL interpreter will generate an error when it gains control (via Step Into, Step Over, Continue, etc.) and will disable the watchpoint.

Watchpoint expressions

A watchpoint expression can be a variable (including array elements), field (including array elements), attribute reference (including chained references), or 4GL built-in function, such as PROPATH. (For a complete list of valid functions, see Table 3–2.) However, the expression might not be a CLOB, BLOB, LONGCHAR, RAW, or MEMPTR variable or field. The Debugger checks only that the watchpoint expression follows the conventions for a valid watch.

Note: Watchpoints are not valid on the name of an array. You must specify a particular array element to watch.

Watchpoint conditions

A condition can be any expression that the 4GL interpreter can evaluate to a logical value. The condition can include references to one or more program variables (including array elements), buffer fields (including array elements), or object attributes; you are not limited to the variable, field, or attribute specified in the watchpoint expression.

When you create a watchpoint, the Debugger checks only that the syntax of the condition is valid. The Debugger cannot verify the existence of variables and fields in the condition, as the references to variables or fields might not be in scope.

Adding a watchpoint to a watch

To add a watchpoint to an existing watch, right-click on a watch in the Watches pane and select Create Watchpoint from the pop-up menu.

The status bar displays the message “Watchpoint created for <expression>” to inform you that the operation was successful. If the operation fails, an alert box displays an error message.

Note: If you want to add a condition to the new watchpoint created on an existing watch, you must bring up the Breakpoints dialog box, select the watchpoint, click the Edit button, and enter the condition in the Edit Breakpoint dialog box.